Skip to content
← 回到文章列表

MSW:把 mock 放到网络层 ​

做前端的大概都经历过这种情况:页面已经画好了,接口文档也对过了,但后端说接口下周才能联调。于是开始造假数据。

最早我是直接在代码里写死一个对象,后来学会了在请求封装里加个 if (import.meta.env.DEV),再后来用 Mock.js、用 json-server、用公司内部的 mock 平台……每种都用过一阵子,每种都有让人难受的地方。直到项目里引入了 MSW(Mock Service Worker),这件事才算基本稳定下来。下面先把老办法的问题过一遍,再讲 MSW 怎么拦请求、怎么用,最后说说它的短处。

先看看传统做法都卡在哪 ​

把常见的 mock 方式按「在哪一层截住请求」排一下,会清楚很多:

应用代码(组件 / store)请求封装(axios 实例、api.ts)网络 API(fetch / XHR / http)Service Worker真实网络服务器(后端 / mock server)写死数据、if (isMock) 分支jest.mock、axios-mock-adapterMock.js 替换 XHR;MSW 的 Node 端在这层拦MSW 的浏览器端在这层拦json-server、vite-plugin-mock、Apifox
越往下拦,应用代码越不知道自己正在被 mock

最省事的是在业务代码里写死,快是快,但也最脏。mock 逻辑和业务逻辑缠在一起,上线前要记得删,删漏了就是事故。我见过不止一次生产环境请求列表里出现 mockUser 的。

再进一步是替换请求库,比如测试里 jest.mock('axios'),或者用 axios-mock-adapter。这样 mock 掉的其实是 axios 这个模块,接口本身没参与。哪天项目把 axios 换成 ky 或原生 fetch,所有 mock 一起失效。更隐蔽的是,请求拦截器、错误处理这些最容易出 bug 的代码,在测试里根本没跑。

Mock.js 这类库直接把全局的 XMLHttpRequest 换成自己的实现,业务代码一行不用改。可它只管 XHR,项目里用 fetch 的请求它拦不到。请求也压根没真正发出去,Network 面板里什么都看不到,调试全靠 console.log。替换后的 XHR 跟原生行为还有出入,上传进度、responseType 之类的细节经常出问题。

本地 mock server 是另一条路,json-server、vite-plugin-mock、webpack devServer 的 before 钩子都算这一类。请求是真发出去了,Network 面板也能看,这点比前面几种强很多。但它多了一个要维护的进程,开发环境和测试环境往往得各配一套;而且跑单元测试时你总不能为了一个用例去起服务,于是测试那边又回到了 jest.mock,两份 mock 各写各的,慢慢就对不上了。

YApi、Apifox 这类远程 mock 平台跟接口文档绑在一起,团队协作挺方便。缺点是依赖网络和平台本身,想模拟「第三次请求返回 500」「这个接口慢 3 秒」这种场景就比较费劲,测试里基本用不上。

MSW 是什么 ​

MSW 全称 Mock Service Worker,是一个 API mock 库。它在网络层拦截请求,业务代码和请求库都不用动。

在浏览器里,它注册一个 Service Worker,让所有从页面发出的请求都先经过这个 Worker;在 Node 里没有 Service Worker,它就在 http、https、fetch 这些底层模块上打补丁。两边用的是同一份请求处理器(handler)。

对应用代码来说,它发的就是一个普通的 fetch('/api/user'),用 axios 还是 fetch 都无所谓,拦截器、错误处理照常执行,只是最后回来的响应是你定义的。

浏览器里是怎么拦的 ​

不少人以为 handler 是跑在 Service Worker 里的,其实不是。mockServiceWorker.js 只负责把截到的请求转发回页面,匹配 handler、生成响应都在页面的主线程里做。

应用代码Service WorkerMSW(页面线程)真实服务器① fetch('/api/user')② postMessage 请求③ 匹配 handler④ 回传 mock 响应⑤ respondWith()没匹配上:原样发给服务器
Service Worker 只负责「截」和「回」,handler 实际运行在页面里

这样一来,handler 就是项目里的普通代码:能 import 共用的类型、工厂函数,甚至 store,能直接打断点,改完跟着热更新,不用操心 Service Worker 的缓存和更新周期。

请求是真的从页面发出去、被 Service Worker 接住的,所以 Network 面板里能看到它,Chrome 会在 Size 一栏标上 (ServiceWorker)。请求头、响应体、耗时都在,查问题时跟看真实请求没什么两样。

上手 ​

以 MSW 2.x 为例。先装上,再把 Worker 脚本生成到静态目录:

bash
pnpm add -D msw
npx msw init public/ --save

--save 会把目录记到 package.json 里,以后升级 MSW 时脚本会自动跟着更新。

然后写 handler。语法很像写一个迷你后端:

ts
// src/mocks/handlers.ts
import { http, HttpResponse, delay } from 'msw'

export const handlers = [
  http.get('/api/user/:id', ({ params }) => {
    return HttpResponse.json({
      id: params.id,
      name: '张三',
      role: 'admin',
    })
  }),

  http.post('/api/login', async ({ request }) => {
    const { username } = await request.json()
    await delay(800) // 模拟慢接口,顺便看看 loading 态

    if (username !== 'admin') {
      return HttpResponse.json({ message: '用户名或密码错误' }, { status: 401 })
    }
    return HttpResponse.json({ token: 'fake-token' })
  }),
]

request 就是标准的 Fetch API Request 对象,返回的也是标准 Response,HttpResponse 只是在它上面加了几个便捷方法。

浏览器端的入口:

ts
// src/mocks/browser.ts
import { setupWorker } from 'msw/browser'
import { handlers } from './handlers'

export const worker = setupWorker(...handlers)

在应用启动前开起来:

ts
// src/main.ts
async function enableMocking() {
  if (!import.meta.env.DEV) return
  const { worker } = await import('./mocks/browser')
  return worker.start({ onUnhandledRequest: 'bypass' })
}

enableMocking().then(() => {
  createApp(App).mount('#app')
})

这里有两个细节。一是用动态 import(),生产构建会把 mock 相关代码整个摇掉,不会混进产物。二是一定要等 worker.start() 完成再挂载应用。Service Worker 注册是异步的,不等的话首屏那几个请求会漏过去,表现就是「刷新一下偶尔拿到真数据」,排查起来挺莫名其妙的。

在 Node 和测试里复用 ​

这是 MSW 最让我舍不得的一点:上面那份 handlers.ts,测试里可以原封不动地拿来用。

handlers.tssetupWorkersetupServer浏览器:本地开发、Storybook、Playwright / CypressNode:Vitest / Jest、SSR、Node 脚本
一份 handler,两种运行环境
ts
// src/mocks/node.ts
import { setupServer } from 'msw/node'
import { handlers } from './handlers'

export const server = setupServer(...handlers)
ts
// vitest.setup.ts
import { beforeAll, afterEach, afterAll } from 'vitest'
import { server } from './src/mocks/node'

beforeAll(() => server.listen({ onUnhandledRequest: 'error' }))
afterEach(() => server.resetHandlers())
afterAll(() => server.close())

测试里 onUnhandledRequest 我习惯设成 'error':任何没被 mock 的请求直接让测试挂掉,免得哪个用例悄悄打到了真实接口。

默认的 handler 写的是正常情况。要测异常分支,就在单个用例里用 server.use() 临时覆盖,afterEach 里的 resetHandlers() 会把它清掉,不影响别的用例:

ts
import { http, HttpResponse } from 'msw'
import { server } from '../mocks/node'

test('接口报错时显示重试按钮', async () => {
  server.use(
    http.get('/api/user/:id', () => {
      return new HttpResponse(null, { status: 500 })
    }),
  )

  render(<UserCard id="1" />)
  expect(await screen.findByRole('button', { name: '重试' })).toBeInTheDocument()
})

这个测试里没有一行在 mock axios 或者 fetch,它只描述了「接口返回 500 时界面该长什么样」。组件内部用什么库发请求、有没有拦截器,都可以随便改,以后重构请求层,这些测试一行都不用动。

对比一下 ​

写死 / 改代码替换请求库Mock.js本地 mock serverMSW
侵入业务代码是测试代码里要 mock 模块否否(要改代理配置)否
Network 面板可见否否否是是
支持 fetch看实现看库否是是
开发和测试共用否否勉强很难是
额外进程无无无要起服务无
换请求库后还能用否否只要还是 XHR是是
团队其他人 / 其他端能用否否否是否

最后一行是 MSW 比不过 mock server 的地方,下面会说到。

MSW 的不足 ​

用了两年多,踩过的坑和它天生做不到的事,大概有这些:

最大的限制是它只服务当前这个前端应用。MSW 的 mock 只存在于你这个页面(或这个 Node 进程)里。移动端同事、另一个前端项目、用 Postman 调接口的测试同学,都看不到这份 mock。如果你需要的是「整个团队共享一套假接口」,mock server 或者 mock 平台更合适。

Service Worker 本身也有环境限制,只能在 HTTPS 或 localhost 下注册。用局域网 IP 在手机上打开开发环境,Service Worker 会注册失败,MSW 也就不起作用了。另外浏览器里 Shift + 刷新 会跳过 Service Worker,有时候同事说「mock 怎么不生效了」,其实就是这个原因。

mockServiceWorker.js 要跟库版本保持一致。这个文件是提交在仓库里的,升级 MSW 后如果没更新它,控制台会给出版本不匹配的警告,严重时直接拦不住请求。前面 init 时加 --save 就是为了让它自动跟着更新。

handler 和真实接口会慢慢走样。这个问题所有 mock 方案都有,MSW 也没解决。后端改了字段,handler 不会自己知道。我的做法是让 handler 的返回值套上从 OpenAPI 生成的类型,至少字段对不上时 TypeScript 会报错。社区里也有直接从 OpenAPI 文档生成 handler 的工具,接口多的话可以考虑。

SSR 项目要配两套。像 Nuxt、Next.js 这种,服务端渲染时发的请求在 Node 里,水合后发的请求在浏览器里,两边得分别启动 setupServer 和 setupWorker。handler 能共用,但启动时机要各自处理,第一次配的时候会有点绕。

最后,团队里没接触过 Service Worker 的同学,遇到问题时不太知道从哪查。不过 MSW 的报错信息写得很好,大部分情况下控制台会直接告诉你哪个请求没被处理、该怎么写 handler。

怎么选 ​

我自己的判断标准比较简单:

  • 只是给当前前端项目开发和写测试用,直接上 MSW,我还没找到更好的选择。
  • 需要给多个端、多个团队提供统一的假接口,就用 mock 平台或 mock server。前端项目里可以再叠一层 MSW 处理测试和边界场景,两者不冲突。
  • 老项目全是 XHR,Mock.js 用得好好的,没必要为了换而换,等哪天要写测试了再迁也不迟。

最后更新: